Inside Macintosh: QuickDraw GX Programmer's Overview / Part 2 - The QuickDraw GX Programming Cookbook

Chapter 4 - Using the QuickDraw GX Environment

Setting Up Type Validation and Error Handling

This programming recipe discusses how you can initialize certain debugging facilities of QuickDraw GX. You should follow the steps described in the previous recipe, "Initializing QuickDraw GX," which begins on page 135, before using this recipe.

QuickDraw GX allows you to install a different error-handling function for each of the three types of errors--errors, warnings, and notices. This recipe shows how to install three simple error-handling functions that drop into your debugger and specify which error, warning, or notice occurred.

This recipe also shows how you can specify that QuickDraw GX is to perform type validation. For example, you can specify that QuickDraw GX examine the objects you pass to QuickDraw GX functions and determine whether they contain valid data.

Overview of Recipe Steps

The steps in this recipe show you how to:

1. Provide error-handling functions
2. Enable type validation

The steps of this recipe are appropriate while you are debugging your applica-
tion. However, when your application is debugged and ready to ship, you should not follow the steps described here. The non-debugging version of QuickDraw GX posts a fewer number of errors and warnings, does not post any notices, and does not perform type validation. Therefore, the final version of your application is required to handle fewer errors and warnings; it does not have to handle notices at all and it does not have to enable type validation.

Also, if you have extensively debugged your application, it shouldn't encounter any warnings and should encounter only a handful of errors, such as out_of_memory. (You can find the complete list in the "graphics errors.h" file). When you are preparing your final application, you should provide your own error handler to handle these errors.

Functions Used in This Recipe

QuickDraw GX functions used in this recipe:

GXSetUserGraphicsError	"Errors, Warnings, and Notices" QuickDraw GX Environment and Utilities
GXSetUserGraphicsWarning	"Errors, Warnings, and Notices" QuickDraw GX Environment and Utilities
GXSetUserGraphicsNotice	"Errors, Warnings, and Notices" QuickDraw GX Environment and Utilities
GXSetValidation	"QuickDraw GX Debugging" QuickDraw GX Environment and Utilities
GXValidateShape	"QuickDraw GX Debugging" QuickDraw GX Environment and Utilities

This recipe gives a brief description of these functions; you can find complete reference information for these functions in the Inside Macintosh suite of books.

This recipe also uses functions from the QuickDraw GX libraries:

SetGraphicsLibraryErrors	graphics debug library
SetGraphicsLibraryNotices	graphics debug library

Recipe Step Descriptions

In this section, each step of the recipe is described individually.

1. Provide error-handling functions

   QuickDraw GX provides three functions for you to specify error-handling functions:

   • The GXSetUserGraphicsError function allows you to provide a function to handle errors.
   • The GXSetUserGraphicsWarning function allows you to provide a function to handle warnings.
   • The GXSetUserGraphicsNotice function allows you to provide a function to handle notices.

     With these functions, you can install application-defined functions that QuickDraw GX calls when it encounters an error condition.

     QuickDraw GX also provides the graphics debug library, which includes functions you might want to use while debugging your program. You can use functions from this library to install simple error-handling functions
     that drop into your debugger and specify which error, warning, or notice occurred. Two commonly used library functions are:

   • The SetGraphicsLibraryErrors library function installs a function to handle errors and warnings.
   • The SetGraphicsLibraryNotices library function installs a function to handle notices.

     The error-handling functions installed by these functions are relatively simple; they call the function DebugStr to drop into your debugger and display a message. For example, if you use these library functions to install error handlers and your application encounters a parameter_out_of_range error, QuickDraw GX drops into your debugger and displays the message

     GRAPHICS ERROR: parameter_out_of_range

     You can then use your debugger and the QuickDraw GX GraphicsBug debugger to determine the source of the error and debug your application.

2. Enable type validation

   The debugging version of QuickDraw GX provides many features that help you find bugs in your program. For example, QuickDraw GX can perform validation--that is, it can confirm whether the object references you send to QuickDraw GX functions contain valid data. QuickDraw GX has three different levels of validation:

   • Type validation confirms that the object references you provide to QuickDraw GX functions refer to valid objects. This level of validation also confirms that the objects are the correct type for the function.
   • Structure validation performs type validation and also confirms that the properties of the objects contain valid data.
   • All-object validation performs type and structure validation for all objects in the graphics heap.

     QuickDraw GX also allows you to specify when it should perform validation:

   • Public validation allows you to specify that QuickDraw GX is to validate your object references whenever your application calls a QuickDraw GX function.
   • Internal validation allows you to specify that QuickDraw GX is to validate all object references whenever any QuickDraw GX function is called--even when QuickDraw GX calls its own internal functions.
   • Specific object validation allows you to perform a specific, one-time validation of a single object reference.

     You use the GXSetValidation function to specify which level of validation you want QuickDraw GX to perform. For example, when debugging you typically want to perform at least this level of validation:

     GXSetValidation(gxPublicValidation | gxTypeValidation);

     Validation does affect the performance of your application. For this reason, you might want to limit validation to specific areas of code. To turn valida-
     tion off, you call

     GXSetValidation(gxNoValidation);

     If you want to validate a specific object reference, but not enable object validation for every function call, you can use the GXValidateShape function. This function validates a single object reference--for example,
     the line of code

     GXValidateShape(myGXShape);

     validates the object reference contained in the variable myGXShape. If any of the information referenced by this variable is not valid, the function posts a validation error.

Related Recipes

For information related to initializing the debugging facilities of QuickDraw GX, see these recipes:

• "Initializing QuickDraw GX," on page 135, shows you how to determine whether QuickDraw GX is available to your application and, if so, how to initialize the graphics and printing parts of QuickDraw GX.
• "Exiting QuickDraw GX," on page 147, shows how to deallocate your graphics client heap and close down your application's connection to the QuickDraw GX world.

The recipes in Chapter 6, "Handling Graphics," and in Chapter 7, "Handling Typography," show you how to create and manipulate QuickDraw GX objects that you can validate during the process of debugging your application.

Printing errors work differently than errors, warnings, and notices. See Chapter 8, "Printing," for more information.